Macwelt 1/Macwelt DVD 1.toast/Web-Publishing/HTML-Editoren/Alpha ƒ/Help/MacPerl Help

Text File | 2000-08-23 | 20.7 KB | 643 lines

MacPerl Support in Alpha

                                               version: 3.3
                                               created: 07/18/95 {06:15:07 pm}
                                           last update: 08/23/00 {03:13:34 pm}

          Introduction


This document describes the use of the MacPerl menu in Alpha.  The MacPerl
menu was written to allow Alpha to act as a front end for Matthias
Neeracher's standalone MacPerl application and to make it possible to
"attach" Perl scripts to Alpha.  It provides a number of features designed
to make the use and development of Perl scripts on the Mac more convenient.
These are detailed in the rest of this document (most easily navigated
using the "M" menu on the sidebar), but here's a quick overview:

    Editing Perl scripts...

• Perl keywords and special variables are colorized in Perl mode.

• The Perl 4 man page is provided as an on-line reference,
  available as the file "Perl Commands" in Alpha's Help menu; it has
  been colorized and indexed to make it easy to read and navigate.

• The man page can be referenced by command-double-clicking a
  highlighted Perl keyword or special variable in your Perl script.

• Source files mentioned in require statements can be opened by
  command-double-clicking as well.

    Running Perl Scripts...

• MacPerl scripts can be run directly from Alpha - a script can be
  a text window in Alpha, a highlighted selection from a window, or a
  disk file.

• You can save scripts as MacPerl droplets and runtime applications
  directly from Alpha.

• Perl scripts that read from standard input and write to standard
  output may be used to process text in Alpha's text windows.

    Debugging Perl scripts...

• When a script fails, the error messages are displayed and the
  script is brought up with the line that caused the error highlighted.

• A flag can be set to cause scripts to run under the Perl
  debugger (without modifying the script).


Currently, no explicit support or documentation is provided for Perl 5, but
this will follow once a stable port of Perl 5 to the 68k Macintosh emerges.

Instructions for obtaining the MacPerl application are given further below.


          Installation


No special installation procedure is required before using this package.
However, there are a couple of things that you may need to do to configure
things for your particular machine.


               MacPerl application and library


Alpha needs to know where to find your MacPerl application in order to
interact with it, and will automatically prompt you to locate it if it
doesn't know where it is.  You can always check and/or change the path that
Alpha uses by selecting the "MacPerl" preference, available in the menu
item "Config --> Mode Prefs --> Preferences".

When opening "require"d source files via the command-double-click
mechanism, Alpha will always look in the "lib" folder in the MacPerl
application directory.  To have Alpha look for library files elsewhere, you
can specify an additional personal library folder, using the "MacPerl lib
folder" preference in "Mode:App Paths" menu.


               Text Filters Setup


If you want to use Perl scripts to process Alpha text buffers (see Text
Filters), you'll need to arrange that the Perl menu is visible while you're
in Text mode.  While in Text mode, select "Set Mode Menus…" from the "√"
pop-up menu on the side-bar and command-click on "perlMenu" in the list of
menus shown.  The little camel icon should appear on the menu bar when
you're done.

The MacPerl menu contains a hierarchical submenu of preattached scripts to
be used as text filters.  A sample collection of such scripts is
distributed with Alpha in the ":Tcl:UserCode:Text Filters:" folder.  You
can specify your own folder of scripts using "MacPerl Text Filters folder"
entry in "Mode:App Paths" menu.

               Option flags

There are a handful of flags you can set to modify the way Alpha and
MacPerl interact while running Perl scripts.  These can be set from
either the MacPerl menu or the "√" pop-up menu on the side-bar.  They're
described in detail below.


          Perl Mode


Perl mode is entered automatically whenever you open a file with a ".pl" or
".ph" suffix; you can also invoke it explicitly using the modes menu in the
status bar.  A "Perl Example.pl" syntax file is available for exploring
some of the mode's features and the Perl menu.

Perl mode offers a number of features supporting the editting
and debugging of Perl scripts:


               Basic language support


• Perl keywords and special variables appear in blue in Perl mode.

• A single line or a selected block of lines may be commented out by
  using the "Comment Line" command under the "Convert" menu.  Lines
  are uncommented using "Uncomment Line", which appears in the "Convert"
  menu when the option key is held down.

• Alpha will create an index of all subroutines in your Perl script when
  you select "Mark File" from the Marks menu on the sidebar (the "{}"
  button).  Once created this index is saved with your file.

  When you open a Perl script that hasn't already been indexed, an index
  is automatically created.


               Command-double-clicking


A simple form of hypertext help is invoked by double-clicking on certain
pieces of text while the command key is held down:

• The online man page can be referenced by command-double-clicking a
  highlighted Perl keyword or special variable in your Perl script.

  Most of the clickable keywords and variables will be colored blue.
  Special variables containing alphabetic characters, .e.g. @ARGV,
  are also clickable but are not colored.

• Command-double-clicking on the name of the source file in a require
  statement will cause that file to be opened by Alpha.

  Alpha will look for the file in the current script's folder, in your local
  library folder and in the MacPerl lib folder (in that order).  The local
  lib folder may be specified interactively by the user (see Installation).


               Mode Preferences


A more complete set of Perl option flags are also settable through the menu
item "Config --> Mode Prefs --> Preferences " menu item (while you're in
Perl mode).

    perlAutoSwitch

(same as "Auto Switch" under "General Options")

    perlGetOutput

(same as "Retrieve Output" under "General Options")

    perlOverwrite

(same as "Overwrite Selection" under "Filter Options")

    perlPromptArgs

(same as "Prompt For Args" under "General Options")

    perlUseDebug

(same as "Use Debugger" under "General Options" )

    perlUsebuffer

(same as "Apply To Buffer" under "Filter Options")

    perlRecycleOutput

If selected, output returned by Macperl overwrites previous output in the
"* Perl Output *" window in Alpha, instead of going into a new window.

There are also two additional preferences that may be examined:

    perlLastFilter

Contains the location of the last text-filter script used.

    perlCmdlineArgs

Contains the last command-line options supplied.

Note these are only passed to scripts when the "Prompt for Args" option is
active.


          MacPerl Menu


Alpha's MacPerl menu allows a number of actions.  These are ...

               MacPerl interaction


    Macperl

Switch to the MacPerl application.


               Tell Macperl ...


    Open In Macperl

Open the current document in MacPerl.

    Save As Droplet

Save the current document as a MacPerl droplet.

    Save As Droplet

Save the current document as a MacPerl runtime script.

    Save As CGI

Save the current document as a MacPerl CGI applet.

A bug in the AEGizmos package makes it impossible to create CGI applets
directly from Alpha at this point.  You will have to open the script in
MacPerl and save it from there.

    Open Output Window

Retrieve the contents of MacPerl's main output window into a new window
under Alpha.

    Close Output Window

Close MacPerl's main output and debugger windows.

    Quit

Force the MacPerl application to quit.



               Running Perl Scripts


    Run The Selection

Execute the selected text as a Perl script.

    Run The Buffer

Execute the current text window as a Perl script.

    Save And Run

Save the current window and run the saved file as a Perl script.  (see
Current Directory)

    Run A File

Run a selected disk file as a Perl script.

               Applying Text Filter Scripts


    Text Filters

A hierarchical menu of "preattached" scripts to use as text filters.  When
a script is selected from this menu, it is immediately applied to the
current text window.

The menu is built from the contents of a user-selected folder.  The folder
is chosen using the "Mode:App Paths" menu command on the main menubar or
the "Text Filters Folder" command under the Macperl "Filter Options"
submenu (below).

    Select Buffer As Filter

Select one of the open text windows to use as the text filter script.

    Select File As Filter

Select a file to use as the text filter script.

    Repeat Last Filter

Run again the last filter that was used.

If the contents of the file or buffer has changed, the new script is run.


               Option flags


    General Options
    ---------------

Flags that control Alpha's behavior when executing ordinary scripts (not
text filters).

    Retrieve Output

Automatically retrieve any output written to the MacPerl output window and
display it in a new window under Alpha.  (same as "perlGetOutput")

If the mode variable "perlRecycleOutput" is set, the previous output window
is overwritten.

    Auto Switch

Switch to MacPerl while scripts are being executed.  Otherwise, Alpha
remains frontmost until the script finishes.  (same as "perlAutoSwitch")

    Prompt For Args

Have Alpha prompt you for command-line arguments to be passed to the
script.  (same as "perlPromptArgs")

    Use Debugger

Force the script to run under the MacPerl debugger.  (same as
"perlUseDebug")

Control is automatically switched to MacPerl when the debugger is used.


    Filter Options
    --------------

Flags controlling the behavior of text filters mechanism.

    Apply To Buffer

Apply the filter to the entire current text window; otherwise, only the
selected text is used.  (same as "perlUseBuffer")

    Overwrite Selection

When checked, the output from the text filter script will replace the input
text in the original window.  Otherwise, the output is written into a new
window.  (same as "perlOverwrite")

    Text Filters Folder

Select the folder from which the Text Filters menu is built.  (You can also
use the "Mode:App Paths" menu.)

    Rebuild Filter Menu

Reconstruct the "Text Filters" menu from the contents of the designated
"Text Filters" folder.




    ======================================================================


          Running Scripts


Running scripts using the MacPerl menu is pretty straightforward.  You can
send the current selection, the entire current buffer, or a disk file to
MacPerl for execution as a Perl script; the result will be the same as if
you ran the script from MacPerl itself.  Here are listed some important
points to remember when running Perl scripts using the MacPerl menu.

               Input and Output


• Except for text filter scripts, the standard input for your script
  is taken from the keyboard (while MacPerl is in the foreground) and
  standard output goes to MacPerl's output window.

  If you need to interact with the script while it's running, make sure
  that you've selected the "AutoSwitch" flag under "General Options".

• To get the output from your script, select the "Retrieve Output"
  flag under "General Options", this will cause Alpha to copy any output to
  Macperl's standard output window back into Alpha after your script has
  completed.  You can always do this manually by using the "Get Output
  Window" command under the "Tell Macperl…" submenu.

  Again, if you need to see the results while the script is running, use
  AutoSwitch" to bring MacPerl to the foreground during script execution.

               Current Directory


For the purpose of resolving relative file references, etc., within your
script, it's important to understand how the current directory of the
running script (as returned by `pwd` ) is determined.

• If you run a script file (using "Run A File"), then the folder containing
  that file is the current folder.

• If you run a script from a text buffer (using "Run The Buffer" or "Run
  The Selection") , it is as though you ran it directly from a window in
  the MacPerl application, and so the current directory your script sees
  is the MacPerl application folder.

• If you run a script from a buffer using the "Save and Run" command,
  then the script is first saved to disk and then executed as a script
  file.  In this case, the current directory is that of the script file.


               Command-line Args


• If the menu flag "Prompt For Args" is checked, then the user is prompted
  for command-line arguments at the time the script is run.  These will be
  available inside the script through the @ARGV array, as usual.  They are
  also saved in the Perl-mode variable "perlCmdlineArgs", and become the
  default arguments the next time the script is executed.

               Error Messages


• If the script fails for some reason, Alpha will read the error messages
  returned by MacPerl and write them back into a new text window, called
  "* Perl Errors *".

• The script that generated the error is brought up
  and the first line specifically referenced in an error message is
  highlighted.

  Note that error-trapping remains active whether "Retrieve Output" is set
  or not.


               Interrupting a Script


When you run a Perl script from Alpha, Alpha will display the watch cursor
and wait for the reply from Macperl before doing anything else.  There may
be times when this is inappropriate, for instance, if you expect the script
to run for a long time or if you think the script is misbehaving for some
reason.

• You can always tell Alpha to stop waiting for a script to finish by
  hitting "Cmd-.".

  This does not abort the script itself; to do that you'll have to switch
  over to MacPerl to terminate the script there, as well.

• When you interrupt a script in this way, Alpha will no longer
  automatically get the output or error messages from MacPerl, when and if
  the script does finally terminate.

  You can always retrieve the contents of the output window yourself using
  "Get Output Window" from the "Tell MacPerl…" submenu or simply by
  switching over to Macperl itself.

There are some simple causes for a hung script.  For instance, if MacPerl
is configured to check for "#!"  lines in scripts and yours doesn't have
one, it will put up a dialog asking whether or not to procede.  If you
didn't switch over to MacPerl when the script was run, you have know way of
knowing this, and so you and Alpha may end up just sitting there waiting.


          Text Filters


Perl is, among other things, a powerful tool for extracting and rewriting
data from text files.  On a Unix system, one would typically write
text-processing scripts to read from "standard input" and write to
"standard output", taking advantage of command-line i/o redirection to
specify the actual input and output files used at any given time.  On the
Mac, the typical absence of a command-line interface makes it harder to use
this elegant method.

The MacPerl menu in Alpha makes it possible to use scripts that read from
standard input and write to standard output to process text buffers in
Alpha directly.  Any text window can be used as standard input and standard
output can either be directed back to that same window or to a newly
created one.  The script used may either be a disk file or yet another
Alpha text window.


               Applying a Text Filter


The procedure for using Perl text filters in Alpha is simple:

1. Bring the text window you want to operate on to the front and select
   (highlight) the text that will be the input to the script.

 • If the "Apply To Buffer" option is selected, then the entire text
   window will be used as input and any text selection is ignored.

 • Only complete lines are used as input.  The text used will be extended
   to include all of the lines on which the selected text lies.

2. Select a Perl script using one of the commands, "Select Buffer As
   Filter", "Select File As Filter" or "Repeat Last Filter" from the Perl
   menu, or by choosing one of the scripts listed in the "Text Filters"
   submenu.

 • You can see the name of the last script used by examining the
   variable "perlLastFilter" under the "√" menu in Perl mode. This
   is the script that will be used if you use "Repeat Last Filter"

 • If the "Prompt For Args" option has been selected, you'll be given
   a dialog box to type in the command-line arguments for the script.

3. The output of the script is written back out, either in the place of
   the input text (if the "Overwrite Selection" option is selected) or into
   a new text window.

 • As always, Alpha's unlimited undo capability let's you recover if you
   accidently overwrite the input text when you didn't want to.

 • If the script halts on an error, the filter operation is aborted
   and any error messages are displayed in a new window.


The ability to take the script itself from a text window allows simple
one-time scripts to be created and applied on the fly.  This can be very
useful because, even with the overhead to start up MacPerl, large-scale
global search-and-replace operations (hundreds of replaces) can be
substantially faster in MacPerl than in Alpha.  Also, you might find it
easier to apply a series of regular expression substitutions using a
single, short Perl script, rather than a number of separate "Find" and
"Replace All" commands in Alpha.


               Preattached Scripts


Frequently used text filter scripts can be conveniently accessed by placing
them in a folder called "Text Filters" within the MacPerl application
folder.  When the MacPerl menu is first created, it looks in this folder
and builds a hierarchical submenu from the names of the scripts that it
finds.  Note that it will also create a "Text Filters" folder if one
doesn't already exist.

A sampling of useful :-) Perl scripts is distributed with Alpha in the
folder ":Tcl:UserCode:Text Filters".

Of the scripts in the sample collection, the "Text Munging" scripts
("shuffle", "sort lines", "travesty", and "wordcount") were taken from the
Camel book (Programming Perl).  The "s2p" script is my adaptation of the
standard code that converts Unix "sed" scripts to Perl (it was modified to
work without using the C preprocessor.)  "Strip Mail Headers" takes e-mail
files and edits out any header lines but the few that I typically care
about ("From:, "Date:", etc..).  "CC To BibTeX" is a script I use that
takes listings from the online "Current Contents" database and rewrites
them as BibTeX database entries.  To try it out, select (highlight) the
sample Current Contents citation below and choose "CC To BibTeX" from the
"Text Filters" submenu (make sure that "Apply To Buffer" is _not_ checked
before you do!)

288. VOS MH; LAMBRY JC; ROBLES SJ; YOUVAN DC; and others.
       FEMTOSECOND SPECTRAL EVOLUTION OF THE EXCITED STATE OF BACTERIAL
     REACTION CENTERS AT 10-K.
       PROCEEDINGS OF THE NATIONAL ACADEMY OF SCIENCES OF THE UNITED STATES OF
     AMERICA, 1992 JAN 15, V89 N2:613-617.


          MacPerl application


MacPerl was written (ported to the Mac) by

          Matthias Neeracher <[e-mail]>, and
          Tim Endres <[e-mail]>.

If you don't already have MacPerl, it's available by anonymous ftp

  <ftp://ftp.switch.ch/software/mac/perl> ,  or
  <ftp://ftp.share.com/pub/macperl>


More information about MacPerl is available from the MacPerl Q&A page,

  <http://err.ethz.ch/members/neeri/macintosh/perl-qa.html> ,

Hal Wine's official MacPerl FAQ,

  <ftp://ftp.netcom.com/pub/ha/hal/MacPerl/>

and Sandra Silcott's MacPerl Primer,

  <http://www.unimelb.edu.au/~ssilcot/macperl-primer/home.html>

which contains useful hints and sample scripts.


          Bugs, etc.


Comments and suggestions regarding this package are always welcome.  If
there's something that bothers you, or some additional capability that
you'd like to see, let me know and I'll see what I can do.

Bug reports and any other comments should be directed to

Author:       Tom Pollard    <[e-mail]>

Contributors: Dan Herron     <[e-mail]>
              David Schooley <[e-mail]>
              Vince Darley   <[e-mail]>
              Martijn Koster <[e-mail]>
              Rob Calhoun    <[e-mail]>

    ======================================================================


          Version History


See the "perlVersionHistory.tcl" file for the latest changes.



Author: Tom Pollard
e-mail: <[e-mail]>

MacPerl Help file updated by Craig Barton Upright

E-mail: <[e-mail]>
  mail: Princeton University,  Department of Sociology
        Princeton, New Jersey  08544
   www: <http://www.princeton.edu/~cupright/>